package tau.adx.common.adn;

import java.util.Map;

import tau.adx.common.advertisers.Advertiser;
import tau.adx.common.bids.bundles.AdxBidBundle;
import tau.adx.common.contracts.MonthlyContract;

/**
 * The ad networks are implemented by the competing agents of the game
 * (everything else is simulated by a game server). Every period each ad network
 * <i>n</i> is contracted by a set <i>Dn</i> of one or more advertisers to run
 * their campaigns. The ad network bids for each impression opportunity on user
 * <i>u</i> (on behalf of one of its contracted advertisers), and for every
 * impression won and presented to user u pays the auction resulting price
 * <i>c(u)</i>. <br>
 * Each implementation of and Ad Netowrk must include the following functions:
 * <ul>
 * <li>{@link #registerMonthlyContract(MonthlyContract)}</li>
 * <li>{@link #getNextDailyBidBundles()}</li>
 * </ul>
 * 
 * @author greenwald
 * 
 */
public interface AdNetwork {

	/**
	 * Registers an {@link Advertiser advertiser's} {@link MonthlyContract} with
	 * the <b>Ad Network</b>. Updates
	 * {@link MonthlyContract#setAdNetwork(AdNetwork)} with itself.
	 * 
	 * @param monthlyContract
	 *            A {@link MonthlyContract} required by the {@link Advertiser}.
	 */
	public void registerMonthlyContract(MonthlyContract monthlyContract);

	/**
	 * Generates a new {@link AdxBidBundle bid bundle} for the next <b>day</b>
	 * in the <b>adx</b> system, for each registered {@link Advertiser}.
	 * 
	 * @return Next day's {@link AdxBidBundle}.
	 */
	public Map<Advertiser, AdxBidBundle> getNextDailyBidBundles();

	/**
	 * @return The network's name.
	 */
	public String getName();
}
